# Environment API

在这里你可以找到所有与 environment 相关的 API。

> 参考 [多环境构建](/guide/advanced/environments) 了解更多。

## Environment Context

Environment context 是一个只读对象，提供一些和当前环境有关的上下文信息。

在 Rsbuild 的 [Plugin hooks](/plugins/dev/hooks#plugin-hooks) 中，你可以通过 `environment` 或 `environments` 入参获取 environment context 对象。

```ts
type EnvironmentContext = {
  name: string;
  browserslist: string[];
  config: NormalizedEnvironmentConfig;
  distPath: string;
  entry: RsbuildEntry;
  htmlPaths: Record<string, string>;
  tsconfigPath?: string;
};
```

### name

当前环境的唯一名称，用于区分和定位环境，对应于 [environments](/config/environments) 配置中的 key。

- **类型：** `string`
- **示例：**

```js
api.modifyRspackConfig((config, { environment }) => {
  if (environment.name === 'node') {
    // modify config for node environment
  }
  return config;
});
```

### browserslist

当前环境设置的目标浏览器范围。详见 [设置浏览器范围](/guide/advanced/browserslist)。

- **类型：** `string[]`
- **示例：**

```js
api.modifyRspackConfig((config, { environment }) => {
  console.log(environment.browserslist);
  return config;
});
```

### config

当前环境使用的 Rsbuild 配置（经过归一化处理）。

- **类型：**

```ts
type NormalizedEnvironmentConfig = DeepReadonly<{
  dev: NormalizedDevConfig;
  html: NormalizedHtmlConfig;
  tools: NormalizedToolsConfig;
  source: NormalizedSourceConfig;
  server: NormalizedServerConfig;
  output: NormalizedOutputConfig;
  plugins?: RsbuildPlugins;
  security: NormalizedSecurityConfig;
  performance: NormalizedPerformanceConfig;
  moduleFederation?: ModuleFederationConfig;
}>;
```

- **示例：**

```js
api.modifyRspackConfig((config, { environment }) => {
  // Rspack
  console.log(config);
  // Rsbuild config for current environment
  console.log(environment.config);
  return config;
});
```

### distPath

构建产物输出目录的绝对路径，对应 RsbuildConfig 中的 [output.distPath.root](/config/output/dist-path) 配置项。

- **类型：** `string`
- **示例：**

```js
api.modifyRspackConfig((config, { environment }) => {
  console.log(environment.distPath);
  return config;
});
```

### entry

构建入口对象，对应 [source.entry](/config/source/entry) 选项。

- **类型：**

```ts
type RsbuildEntry = Record<string, string | string[] | EntryDescription>;
```

- **示例：**

```js
api.modifyRspackConfig((config, { environment }) => {
  console.log(environment.entry);
  return config;
});
```

### htmlPaths

HTML 产物的路径信息。

该 API 会返回一个对象，对象的 key 为 entry 名称，value 为 HTML 文件在产物目录下的相对路径。

- **类型：**

```ts
type htmlPaths = Record<string, string>;
```

- **示例：**

```js
api.modifyRspackConfig((config, { environment }) => {
  console.log(environment.htmlPaths);
  return config;
});
```

### tsconfigPath

tsconfig.json 文件的绝对路径，若项目中不存在 tsconfig.json 文件，则为 `undefined`。

- **类型：**

```ts
type TsconfigPath = string | undefined;
```

- **示例：**

```js
api.modifyRspackConfig((config, { environment }) => {
  console.log(environment.tsconfigPath);
  return config;
});
```

## Environment API

Environment API 包了一些与多环境构建相关的 API。

你可以通过 [rsbuild.createDevServer()](/api/javascript-api/instance#rsbuildcreatedevserver) 或 [dev.setupMiddlewares](/config/dev/setup-middlewares) 使用 environment API，这允许你在服务端获取特定环境下的构建产物信息。

```ts
type EnvironmentAPI = {
  [name: string]: {
    getStats: () => Promise<Stats>;
    loadBundle: <T = unknown>(entryName: string) => Promise<T>;
    getTransformedHtml: (entryName: string) => Promise<string>;
  };
};
```

### getStats

获取当前环境的产物信息。

- **类型：**

```ts
type GetStats = () => Promise<Stats>;
```

- **示例：**

```ts
const webStats = await environments.web.getStats();

console.log(webStats.toJson({ all: false }));
```

### loadBundle

在服务端加载并执行构建产物。该方法会返回入口模块导出的内容。

- **类型：**

```ts
/**
 * @param entryName - 入口名称，和 Rsbuild `source.entry` 的某一个 key 值对应
 * @returns 入口模块的返回值
 */
type LoadBundle = <T = unknown>(entryName: string) => Promise<T>;
```

- **示例：**

```ts
// 加载 `main` 入口的 bundle
const result = await environments.node.loadBundle('main');
```

### getTransformedHtml

获取经过编译和转换后的 HTML 模版内容。

- **类型：**

```ts
type GetTransformedHtml = (entryName: string) => Promise<string>;
```

- **示例：**

```ts
// 获取 main 入口的 HTML 内容
const html = await environments.web.getTransformedHtml('main');
```

该方法会返回完整的 HTML 字符串，包含了所有通过 HTML 插件注入的资源和内容。
